home *** CD-ROM | disk | FTP | other *** search
/ PD Collection CD 1 / PD Collection CD 1.iso / programer2 / icon / Docs / Tr90-5 < prev    next >
Text File  |  1990-07-19  |  53KB  |  1,915 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                  Transporting Version 8 of Icon*
  15.  
  16.  
  17.                         Ralph E. Griswold
  18.  
  19.  
  20.  
  21.  
  22.  
  23.                             TR 90-5c
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.           January 1, 1990; last modified March 29, 1990
  50.  
  51.  
  52.                  Department of Computer Science
  53.  
  54.                     The University of Arizona
  55.  
  56.                       Tucson, Arizona 85721
  57.  
  58.  
  59.  
  60.  
  61. *This work was supported by the National Science Foundation under
  62. Grant CCR-8901573.
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.                  Transporting Version 8 of Icon
  77.  
  78.  
  79.  
  80.  
  81. 1.__Background
  82.  
  83.    The implementation of the Icon programming language is large
  84. and complex [1]. It is, however, written almost entirely in C,
  85. and it is designed to be portable to a wide range of computers
  86. and operating systems.
  87.  
  88.    The implementation was developed on a UNIX* system.  It has
  89. been installed on a wide range of UNIX systems, from mainframes
  90. to personal computers. Putting Icon on a new UNIX system is more
  91. a matter of installation than porting [2].  There presently also
  92. are implementations of Icon for the Amiga, the Atari ST, the
  93. Macintosh, MS-DOS, MVS, OS/2, VM/CMS, and VMS. This document
  94. addresses the problems and procedures for porting Icon to other
  95. operating systems and computers.
  96.  
  97.    The current version of Icon is 8 [3].  All installations of
  98. Version 8 of Icon are obtained from common source code, using
  99. conditional compilation to select system-dependent code. Conse-
  100. quently, transporting Icon to a new system is largely a matter of
  101. selecting appropriate values for configuration parameters, decid-
  102. ing among alternative definitions, and possibly adding some code
  103. that is computer- or operating-system-dependent.
  104.  
  105.    A small amount of assembly-language code is needed for a com-
  106. plete installation.  See Section 7. This code is optional and
  107. only affects co-expressions.  A running version of the language
  108. can be obtained by working only in C.
  109.  
  110.    Transporting Icon to a new system is a fairly complex task,
  111. although there are many aids to simplify the mechanical portions.
  112. Read this report carefully before beginning a port.  Understand-
  113. ing the Icon programming language is helpful during the debugging
  114. phase of a port. See [3-5].
  115.  
  116.  
  117. 2.__Requirements
  118.  
  119. C_Data_Sizes
  120.  
  121.    Icon places the following requirements on C data sizes:
  122.  
  123.  
  124. __________________________
  125. *UNIX is a trademark of AT&T Bell Laboratories.
  126.  
  127.  
  128.  
  129.  
  130.                              - 1 -
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.      +   chars must be 8 bits.
  140.  
  141.      +   ints must be 16, 32, or 64 bits.
  142.  
  143.      +   longs and pointers must be 32 or 64 bits.
  144.  
  145.      +   All pointers must be the same length.
  146.  
  147.      +   longs and pointers must be the same length.
  148.  
  149. If your C data sizes do not meet these requirements, do not
  150. attempt to transport Icon. Call the Icon Project for advice.
  151.  
  152. The_C_Compiler
  153.  
  154.    The main requirement for implementing Icon is a production-
  155. quality C compiler that supports at least the de facto ``K&R''
  156. standard [6].  The term ``production quality'' implies robust-
  157. ness, correctness, the ability to handle large files and compli-
  158. cated expressions, and a comprehensive run-time library.
  159.  
  160.    C preprocessor should conform either to the ANSI C standard
  161. [7] or to the de facto standard for UNIX C preprocessors.  In
  162. particular, Icon uses the C preprocessor to concatenate strings
  163. and substitute arguments within quotation marks. For the ANSI
  164. preprocessor standard, the following definitions are used:
  165.  
  166.         #define Cat(x,y) x##y
  167.         #define Lit(x) #x
  168.  
  169. For the UNIX de facto standard, the following definitions are
  170. used:
  171.  
  172.         #define Ident(x) x
  173.         #define Cat(x,y) Ident(x)y
  174.         #define Lit(x) "x"
  175.  
  176. The following program can be used to test these preprocessor
  177. facilities:
  178.  
  179.         Cat(ma,in)()
  180.         {
  181.            printf(Lit(Hello world\n));
  182.         }
  183.  
  184. If this program does not compile and print Hello world using one
  185. of the sets of definitions above, there is no point in proceed-
  186. ing.  Contact the Icon Project as described in Section 8 for
  187. alternative approaches.
  188.  
  189. Memory
  190.  
  191.    The Icon programming language requires a substantial amount of
  192. memory to run.  The practical minimum is 640Kb.
  193.  
  194.  
  195.  
  196.                              - 2 -
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205. File_Space
  206.  
  207.    The source code for Icon is large - about 1 Mb.  Compilation
  208. and testing require considerably more space.  While the implemen-
  209. tation can be divided into components that can be transported
  210. separately, this approach may be painful.
  211.  
  212.  
  213. 3.__Organization_of_the_Implementation
  214.  
  215.    Icon was developed on a hierarchical file system. To facili-
  216. tate file transfer between different operating systems and to
  217. simplify porting to systems that do not support file hierarchies,
  218. the source code for Icon is provided both in hierarchical form
  219. and in a ``flat'' form in which all files reside in the same
  220. area.  This document applies to both the hierarchical and flat
  221. forms. Some of the descriptions that follow refer to file hierar-
  222. chies. In interpreting this documentation for a flat system, sim-
  223. ply ignore the directories in path specifications; the file names
  224. themselves are the same in the hierarchical and flat version.
  225.  
  226. 3.1__Source_Code
  227.  
  228.    There are two components of Icon:
  229.  
  230.      iconta command processor that converts source-language pro-
  231.           grams into icode, the ``executable binary'' for the
  232.           Icon virtual machine.
  233.  
  234.      iconxan executor for icode, including a run-time system that
  235.           supports the operations of the Icon language.
  236.  
  237.    The files related to the source are packaged in four sections:
  238.  
  239.         h            headers
  240.         icont        files for icont
  241.         iconx        files for iconx
  242.         common       common files1
  243.  
  244. In some forms of the diskette distribution, iconx comes in two
  245. parts, since it is is too large to fit on some kinds of
  246. diskettes.
  247.  
  248.    Appendix A lists the files of each component of Icon. Some
  249. header files are used in both components; these are identified in
  250. the appendix.  The files icont.bat and iconx.bat are scripts that
  251. indicate what files are to be compiled and loaded to produce the
  252. respective components. These scripts were derived from a UNIX
  253. implementation, but they can be adapted easily to other systems.
  254. __________________________
  255. 1Some files are shared by icont and  iconx.  Others  are  in
  256. this  package  for  organizational  reasons because they are
  257. shared by other programs related to Icon.
  258.  
  259.  
  260.  
  261.  
  262.                              - 3 -
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271. 4.__An_Overview_of_the_Porting_Process
  272.  
  273.    The first step in the porting process is to configure the
  274. source code for the new system. This process is described in Sec-
  275. tion 5.1. After this is done, icont and iconx need to be con-
  276. structed.
  277.  
  278.    The process for each component is essentially the same:
  279.  
  280.      +  provide code and definitions that are system-dependent
  281.  
  282.      +  compile the source files and link them to produce execut-
  283.         able binary files
  284.  
  285.      +  test the result
  286.  
  287.      +  debug, iterating over the previous steps as necessary
  288.  
  289.    icont needs to be ported before iconx, since the output of
  290. icont is needed to test iconx.  Of course, bugs in icont may not
  291. show up until iconx is tested.
  292.  
  293.    In addition to this obvious sequence of steps, some aspects of
  294. the implementation may be deferred until the entire system is
  295. running, or they may be implemented in a preliminary manner and
  296. subsequently refined. For example, the assembly-language portion
  297. of iconx is best left unimplemented until the rest of the system
  298. is running.
  299.  
  300.    Considerable frustration can be avoided if problems that come
  301. up can be circumvented with temporary expedients until the major-
  302. ity of the implementation is working properly. Similarly, conser-
  303. vative choices should be made during the initial phases of the
  304. implementation.
  305.  
  306.  
  307. 5.__Conditional_Compilation
  308.  
  309.    Conditional compilation is used extensively in Icon to select
  310. code that is appropriate to a particular installation. Conceptu-
  311. ally, conditional compilation can be divided into two categories:
  312.  
  313.      (1)  Matters related to the details of computer architec-
  314.           ture, run-time system idiosyncrasies, specific C com-
  315.           pilers, and operating-system variants.
  316.  
  317.      (2)  Matters that are specific to operating systems that are
  318.           distinctly different, such as MS-DOS, UNIX, and VMS.
  319.  
  320. 5.1__Parameters_and_Definitions
  321.  
  322.    There are many defined constants and macros in the source code
  323. for Icon that vary from system to system.  The file h/config.h,
  324. which is included at the beginning of every .c file, manages the
  325.  
  326.  
  327.  
  328.                              - 4 -
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337. configuration1. It includes h/define.h and, based on the informa-
  338. tion there, provides appropriate definitions, including defaults
  339. for information that is not specified in define.h.  It is in
  340. define.h that changes and additions for a specific implementation
  341. need to be made.  This file initially contains definitions for a
  342. ``vanilla'' 32-bit system.  If your system closely approximates
  343. such a system, you will have few changes to make to define.h.
  344. Over the range of possible systems, there are many possibilities
  345. as described below.  Do not be intimidated by the large number of
  346. options that follow; only a few are needed for any one implemen-
  347. tation.
  348.  
  349.    The definitions are grouped into categories so that any neces-
  350. sary changes to define.h can be approached in a logical way.
  351.  
  352. Debugging code: Icon contains some code to assist in debugging.
  353. It is enabled by the definitions
  354.  
  355.         #define DeBugTrans       /* debugging code for the translator in icont */
  356.         #define DeBugLinker      /* debugging code for the linker in icont */
  357.         #define DeBugIconx       /* debugging code for the executor */
  358.  
  359. All three of these are automatically defined if DeBug is defined.
  360. DeBug is defined in define.h as it is distributed, so all debug-
  361. ging code is enabled.
  362.  
  363.    The debugging code for the translator consists of functions
  364. for dumping symbol tables (see icont/tsym.c). These functions are
  365. rarely needed and there are no calls to them in the source code
  366. as it is distributed.
  367.  
  368.    The debugging code for the linker consists of a function for
  369. dumping the code region (see icont/lcode.c) and code for generat-
  370. ing a debugging file that is a printable image of the icode file
  371. produced by the linker. This debugging file, which is produced if
  372. the option -L is given on the command line when icont is run,
  373. frequently is useful if problems are encountered in the linker.
  374. See Section 6.
  375.  
  376.    The debugging code for the executor consists of a few validity
  377. checks at places where problems have been encountered in the
  378. past. It also provides functions for dumping Icon values. See
  379. iconx/rmisc.c and iconx/rmemmgt.c.
  380.  
  381. It usually is advisable to leave the debugging code enabled until
  382. Icon is known to be running properly. The code is innocuous and
  383. adds only a few percent to the size of the executable files. It
  384. should be removed by deleting the definition listed above from
  385. define.h as the final step in the implementation.
  386.  
  387. __________________________
  388. 1 config.h includes <stdio.h>, so you should not include  it
  389. elsewhere.
  390.  
  391.  
  392.  
  393.  
  394.                              - 5 -
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403. C preprocessor considerations: If your C preprocessor supports
  404. the ANSI draft standard, add
  405.  
  406.         #define StandardPP
  407.  
  408. to define.h.
  409.  
  410. C compiler considerations: If your C compiler supports the ANSI C
  411. draft standard, add
  412.  
  413.         #define StandardC
  414.  
  415. to define.h.
  416.  
  417.    This has several effects.  One is to provide a typedef for
  418. pointer that is void * rather than char *. It also enables func-
  419. tion prototypes and the use of the void type for functions that
  420. do not return values.
  421.  
  422. C library considerations: If your C compiler has an ANSI C draft
  423. standard C library, add
  424.  
  425.         #define StandardLib
  426.  
  427. to define.h.
  428.  
  429.    Alternatively, if your system has a standard C preprocessor,
  430. compiler, and library, just add
  431.  
  432.         #define Standard
  433.  
  434. which defines StandardPP, StandardC, and StandardLib.
  435.  
  436.    If your C compiler supports the void type but not the ANSI C
  437. draft standard, add
  438.  
  439.         #define VoidType
  440.  
  441. to define.h.
  442.  
  443.    If your C compiler supports function prototypes but not the
  444. ANSI C draft standard, add
  445.  
  446.         #define Prototypes
  447.  
  448. to define.h. This causes function prototypes (in proto.h) to be
  449. used in place of forward declarations. The use of prototypes may
  450. be very helpful in getting Icon to work, especially on systems
  451. with 16-bit ints or unusual pointer representations.  (Function
  452. prototypes are produced using a macro, Params(s). See the defini-
  453. tion of Params(s) in h/config.h and examples of its use in
  454. h/proto.h.)
  455.  
  456.    On some systems it may be necessary to provide a different
  457.  
  458.  
  459.  
  460.                              - 6 -
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469. typedef for pointer than mentioned above. For example, on the
  470. huge-memory-model implementation of Icon for Microsoft C on MS-
  471. DOS, its define.h contains
  472.  
  473.         typedef huge void *pointer
  474.  
  475. If an alternative typedef is used for pointer, add
  476.  
  477.         #define PointerDef
  478.  
  479. to define.h to avoid the default one.
  480.  
  481.    Sometimes computing the difference of two pointers causes
  482. problems.  Pointer differences are computed using the macro
  483. DiffPtrs(p1,p2), which has the default definition:
  484.  
  485.         #define DiffPtrs(p1,p2) (word)((p1)-(p2))
  486.  
  487. where word is a typedef that is provided automatically and usu-
  488. ally is long int.
  489.  
  490.    This definition can be overridden in define.h. For example,
  491. Microsoft C for the MS-DOS large memory model uses
  492.  
  493.         #define DiffPtrs(p1,p2) ((word)(p1)-(word)(p2))
  494.  
  495. If you provide an alternate definitions for pointer differencing,
  496. be careful to enclose all arguments in parentheses.
  497.  
  498. C sizing and alignment: There are four constants that relate to
  499. the size of C data and alignment:
  500.  
  501.         IntBits     (default: 32)
  502.         WordBits    (default: 32)
  503.         Double      (default: undefined)
  504.  
  505. IntBits is the number of bits in a C int. It may be 16, 32, or
  506. 64. WordBits is the number of bits in a C long (Icon's ``word'').
  507. It may be 32 or 64.  If your C library expects doubles to be
  508. aligned at double-word boundaries, add
  509.  
  510.         #define Double
  511.  
  512. to define.h.
  513.  
  514. The word alignment of stacks used by co-expressions is controlled
  515. by
  516.  
  517.         StackAlign  (default: 2)
  518.  
  519. If your system needs a different alignment, provide an appropri-
  520. ate definition in define.h.
  521.  
  522.    Most computers have downward-growing C stacks, for which stack
  523.  
  524.  
  525.  
  526.                              - 7 -
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535. addresses decrease as values are pushed. If you have an upward-
  536. growing stack, for which stack addresses increase as values are
  537. pushed, add
  538.  
  539.         #define UpStack
  540.  
  541. to define.h.
  542.  
  543. Floating-point arithmetic: There are three optional definitions
  544. related to floating-point arithmetic:
  545.  
  546.         Big         (default: 9007199254740092.)
  547.         LogHuge     (default: 309)
  548.         Precision   (default: 10)
  549.  
  550. The values of Big, LogHuge, and Precision give, respectively, the
  551. largest floating-point number that does not loose precision, the
  552. maximum base-10 exponent + 1 of a floating-point number, and the
  553. number of digits provided in the string representation of a
  554. floating-point number. If the default values given above do not
  555. suit the floating-point arithmetic on your system, add appropri-
  556. ate definitions to define.h.
  557.  
  558. Open options: The options for opening files with fopen() are
  559. given by the following constants:
  560.  
  561.         ReadBinary  (default: "rb")
  562.         ReadText    (default: "r")
  563.         WriteBinary (default: "wb")
  564.         WriteText   (default: "w")
  565.  
  566. These defaults can be changed by definitions in define.h.
  567.  
  568. Run-time routines: The support for some run-time routines varies
  569. from system to system.  The related constants are:
  570.  
  571.         IconGcvt    (default: undefined)
  572.         IconQsort   (default: undefined)
  573.         SysMem      (default: undefined)
  574.         index       (default: undefined)
  575.         rindex      (default: undefined)
  576.  
  577.  
  578.    If IconGcvt and IconQsort are defined, versions of gcvt() and
  579. qsort() in the Icon system are used in place of the routines nor-
  580. mally provided in the C run-time system. These constants only
  581. need to be defined if the versions of these routines in your
  582. run-time system are defective or missing.
  583.  
  584.    If SysMem is defined and IntBits == WordBits, the C run-time
  585. routines memcpy() and memset() are used in place of the
  586. corresponding Icon routines memcopy() and memfill().  SysMem is
  587. automatically defined if StandardLib is.
  588.  
  589.  
  590.  
  591.  
  592.                              - 8 -
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.    Different C compilers use different names for the routines for
  602. locating substrings within strings. The source code for Icon uses
  603. index and rindex. The other possibilities are strchr and strrchr.
  604. If your system uses the latter names, add
  605.  
  606.         #define index strchr
  607.         #define rindex strrchr
  608.  
  609. to define.h.
  610.  
  611.    Similarly, Icon uses unlink for the routine that deletes a
  612. file.  The other common name is remove. If your system uses this
  613. name, for example, add
  614.  
  615.         #define unlink remove
  616.  
  617. to define.h.
  618.  
  619. Storage management: Icon includes its own versions of malloc(),
  620. calloc(), realloc(), and free() so that it can manage its storage
  621. region without interference from allocation by the operating sys-
  622. tem. Normally, Icon's versions of these routines are loaded
  623. instead of the system library routines.
  624.  
  625.    Leave things are they are in the initial configuration, but if
  626. your system insists on loading its own library routines, multiple
  627. definitions will occur as a result of the ld in src/iconx.  If
  628. multiple definitions occur, go back and add
  629.  
  630.         #define IconAlloc
  631.  
  632. to define.h. This definition causes Icon's routines to be named
  633. differently to avoid collision with the system routine names.
  634.  
  635.    One possible effect of this definition is to interfere with
  636. Icon's expansion of its memory region in case the initial values
  637. for allocated storage are not large enough to accommodate a pro-
  638. gram that produces a lot of data.  This problem appears in the
  639. form of run-time errors 305-307. Users can get around this prob-
  640. lem on a case-by-case basis by increasing the initial values for
  641. allocated storage by setting environment variables [8].
  642.  
  643.    Icon's dynamic storage allocation system uses three memory
  644. regions.  In some implementations, these regions expand if neces-
  645. sary, allowing memory space to be used in a flexible fashion.
  646. This ``expandable regions'' method relies on the use of brk() and
  647. sbrk() and the system treatment of user memory space as one logi-
  648. cally contiguous region. This method does not work on many sys-
  649. tems that treat memory as segmented or do not support brk() and
  650. sbrk(). On such systems, fixed-sized regions are used.  Since
  651. this is the commonest case,
  652.  
  653.         #define FixedRegions
  654.  
  655.  
  656.  
  657.  
  658.                              - 9 -
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667. is included in define.h initially.  If your system supports brk()
  668. and sbrk(), you may wish to remove this definition in order to
  669. get better utilization of memory.  However, since expandable
  670. regions are more prone to problems than fixed regions, it is wise
  671. to start with the latter and try the former only after everything
  672. else is working.
  673.  
  674. Storage regions: The sizes of Icon's run-time storage regions for
  675. allocated data normally are the same for all implementations.
  676. However, different values can be set:
  677.  
  678.         MaxStatSize (default: 20480 if co-expressions are enabled, else 1024)
  679.         MaxAbrSize  (default: 65000)
  680.         MaxStrSize  (default: 65000)
  681.  
  682. Since users can override the set values with environment vari-
  683. ables, it is unwise to change them from their defaults except in
  684. unusual cases.
  685.  
  686.    The sizes for Icon's main interpreter stack and co-expression
  687. stacks also can be set:
  688.  
  689.         MStackSize  (default: 10000)
  690.         StackSize   (default: 2000)
  691.  
  692. As for the block and string storage regions, it is unwise to
  693. change the default values except in unusual cases.
  694.  
  695.    Finally, with fixed-regions storage management, a list used
  696. for pointers to strings during garbage collection, can be sized:
  697.  
  698.         QualLstSize (default: 5000)
  699.  
  700. Like the sizes above, this one normally is best left unchanged.
  701.  
  702. Allocation size: Normally malloc() is used to allocate space for
  703. Icon's storage regions. This limits region sizes to the value of
  704. the largest unsigned int. Some systems provide alternative allo-
  705. cation routines for allocating larger regions.  To change the
  706. allocation procedure for regions, add a definition for AllocReg
  707. to define.h. For example, the huge-memory-model implementation of
  708. Icon for Microsoft C uses the following:
  709.  
  710.         #define AllocReg(n) halloc((long)n,sizeof(char))
  711.  
  712. Note: Icon still uses malloc() for allocating other blocks.  If
  713. this is a problem, it may be possible to change this by defining
  714. malloc in define.h, as in
  715.  
  716.         #define malloc lmalloc
  717.  
  718. If this is done, and the size of the allocation is not unsigned
  719. int, add an appropriate definition for the type by defining
  720. AllocType in define.h, such as
  721.  
  722.  
  723.  
  724.                              - 10 -
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.         #define AllocType unsigned long int
  734.  
  735.  
  736.    It is also necessary to add a definition for the limit on the
  737. size of an Icon region:
  738.  
  739.         #define MaxBlock n
  740.  
  741. where n is the maximum size allowed (the default for MaxBlock is
  742. MaxUnsigned, the largest unsigned int). It generally is not
  743. advisable to set MaxBlock to the largest size an alternative
  744. allocation routine can return. For the huge-memory-model imple-
  745. mentation mentioned above, MaxBlock is 256000.
  746.  
  747. File name suffixes: The suffixes used to identify Icon source
  748. programs, ucode files, and icode files may be specified in
  749. define.h:
  750.  
  751.         #define SourceSuffix(default: ".icn")
  752.         #define U1Suffix    (default: ".u1")
  753.         #define U2Suffix    (default: ".u2")
  754.         #define USuffix     (default: ".u")
  755.         #define IcodeSuffix (default: "")
  756.         #define IcodeASuffix(default: "")
  757.  
  758. USuffix is used for the abbreviation that icont understands in
  759. place of the complete U1Suffix or U2Suffix. IcodeASuffix is an
  760. alternative suffix that iconx uses when searching for icode files
  761. specified without a suffix. For example, on MS-DOS, IcodeSuffix
  762. is ".icx" and IcodeASuffix is ".ICX".
  763.  
  764.    If values other than the defaults are specified, care must be
  765. taken not to introduce conflicts or collisions among names of
  766. different types of files.
  767.  
  768. Paths: If icont is given a source program in a directory dif-
  769. ferent from the local one (``current working directory''), there
  770. is a question as to where ucode and icode files should be
  771. created: in the local directory or in the directory that contains
  772. the source program. On most systems, the appropriate place is in
  773. the local directory (the user may not have write permission in
  774. the directory that contains the source program).  However, on
  775. some systems, the directory that contains the source file is
  776. appropriate. By default, the directory for creating new files is
  777. the local directory. The other choice can be selected by adding
  778.  
  779.         #define TargetDir SourceDir
  780.  
  781.  
  782. Command-line options: The command-line options that are supported
  783. by icont are defined by Options. The default value (see config.h)
  784. will do for most systems, but an alternative can be included in
  785. define.h.
  786.  
  787.  
  788.  
  789.  
  790.                              - 11 -
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.    Similarly, the error message produced by icont for erroneous
  800. command lines is defined by Usage. The default value, which
  801. should correspond to the value of Options, is in config.h, but
  802. may be overridden by a definition in define.h.
  803.  
  804. Environment variables: If your system does not support environ-
  805. ment variables (via the run-time library routine getenv), add the
  806. following line to define.h:
  807.  
  808.         #define NoEnvVars
  809.  
  810. This disables Icon's ability to change internal parameters to
  811. accommodate special user needs (such as using memory region sizes
  812. different from the defaults), but does not otherwise interfere
  813. with the use of Icon.
  814.  
  815. Character set: If you are porting Icon to a computer that uses
  816. the EBCDIC character set, add
  817.  
  818.         #define EBCDIC 1
  819.  
  820. to define.h.
  821.  
  822. Host identification: The identification of the host computer as
  823. given by the Icon keyword &host needs to be specified in
  824. define.h.  The definition
  825.  
  826.         #define HostStr "unspecified host"
  827.  
  828. is provided in define.h initially.  This definition should be
  829. changed to an appropriate value for your system.
  830.  
  831. Exit codes: Exit codes are determined by the following defini-
  832. tions:
  833.  
  834.         NormalExit  (default: 0)
  835.         ErrorExit   (default: 1)
  836.  
  837.  
  838. Memory monitoring: The number of bytes for reporting block sizes
  839. in allocation history files produced by memory monitoring [9] is
  840. determined by
  841.  
  842.         MMUnits     (default: WordSize)
  843.  
  844. A smaller value is needed if the size of any Icon block is not an
  845. even multiple of WordSize. This occurs, for example, on computers
  846. with 80-bit (1-1/2 word) floating-point numbers, in which case
  847. the value of MMUnits should be defined to be 2.
  848.  
  849. Clock rate: Hz defines the units returned by the times() function
  850. call.  Check the documentation for this function on your system.
  851. If it says that times are returned in terms of 1/60 second, no
  852. action is needed. Otherwise, define Hz in define.h to be the
  853.  
  854.  
  855.  
  856.                              - 12 -
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865. number of times() units in one second.
  866.  
  867.    The documentation may refer you to an additional file such as
  868. /usr/include/sys/param.h. If so, check the value there, and
  869. define Hz accordingly.
  870.  
  871. Executable Images: If you have a BSD UNIX system and want to
  872. enable the function save(s), which allows an executable image of
  873. a running Icon program to be saved [3], add
  874.  
  875. Keyboard functions: If your system supports the keyboard func-
  876. tions getch(), getche(), and kbhit(), add
  877.  
  878.         #define KeyboardFncs
  879.  
  880. to define.h.
  881.  
  882. System function: If your system supports the system() function
  883. for executing command line, add
  884.  
  885.         #define SystemFnc
  886.  
  887. to define.h.
  888.  
  889. Dynamic hashing:
  890.  
  891.    Four parameters configure the implementation of tables and
  892. sets:
  893.  
  894.         HSlots      Initial number of hash buckets; it must be a
  895.                     power of 2
  896.  
  897.         HSegs       Maximum number of hash bucket segments
  898.  
  899.         MaxHLoad    Maximum allowable loading factor
  900.  
  901.         MinHLoad    Minimum loading factor for new structures
  902.  
  903.    The default values (listed below) are appropriate for most
  904. systems. If you want to change the values, read the discussion
  905. that follows.
  906.  
  907.    Every set or table starts with HSlots hash buckets, using one
  908. bucket segment.  When the average hash bucket exceeds MaxHLoad
  909. entries, the number of buckets is doubled and one more segment is
  910. consumed.  This repeats until HSegs segments are in use; after
  911. that, structure still grows but no more hash buckets are added.
  912.  
  913.    MinHLoad is used only when copying a set or table or when
  914. creating a new set through the intersection, union, or difference
  915. of two other sets.  In these cases a new set may be more lightly
  916. loaded than otherwise, but never less than MinHLoad if it exceeds
  917. a single bucket segment.
  918.  
  919.  
  920.  
  921.  
  922.                              - 13 -
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.    For all machines, the default load factors are 5 for MaxHLoad
  932. and 1 for MinHLoad.  Because splitting or combining buckets
  933. halves or doubles the load factor, MinHLoad should be no more
  934. than half MaxHLoad.  The average number of elements in a hash
  935. bucket over the life of a structure is about 2/3xMaxHLoad, assum-
  936. ing the structure is not so huge as to be limited by HSegs.
  937. Increasing MaxHLoad delays the creation of new hash buckets,
  938. reducing memory demands at the expense of increased search times.
  939. It has no effect on the memory requirements of minimally-sized
  940. structures.
  941.  
  942.    HSlots and HSegs interact to determine the minimum size of a
  943. structure and its maximum efficient capacity.  The size of an
  944. empty set or table is directly related to HSegs+HSlots; smaller
  945. values of these parameters reduce the memory needs of programs
  946. using many small structures.  Doubling HSlots delays the onset of
  947. the first structure reorganization until twice as many elements
  948. have been inserted.  It also doubles the capacity of a structure,
  949. as does increasing HSegs by 1.
  950.  
  951.    The maximum number of hash buckets is HSlotsx(2^(HSegs-1)).  A
  952. structure can be considered ``full'' when it contains MaxHLoad
  953. times that many entries; beyond that, lookup times gradually
  954. increase as more elements are added.  Until a structure becomes
  955. full, the values of HSlots and HSegs do not affect lookup times.
  956.  
  957.    For machines with 16-bit ints, the defaults are 4 for HSlots
  958. and 6 for HSegs.  Sets and tables grow from 4 hash buckets to a
  959. maximum of 128, and become full at 640 elements.  For other
  960. machines, the defaults are 8 for HSlots and 10 for HSegs.  Sets
  961. and tables grow from 8 hash buckets to a maximum of 4096, and
  962. become full at 20480 elements.
  963.  
  964. Optional features: Some features of Icon are optional. Some of
  965. these normally are enabled, while others normally are disabled.
  966. The features that normally are enabled can be disabled to, for
  967. example, reduce the size of the executable files. A negative form
  968. of definition is used for these, as in
  969.  
  970.         #define NoLargeInts
  971.  
  972. which can be added to define.h to disable large-integer arith-
  973. metic. It may be necessary to disable large-integer arithmetic on
  974. computers with a small amount of memory, since the feature
  975. increases the size of iconx by 15-20%.
  976.  
  977.    Examine config.h to see what other features can be disabled
  978. and the definitions to use.
  979.  
  980.    One optional feature that normally is disabled is the ability
  981. to call an Icon program from a C function [10]. This feature can
  982. be enabled by adding
  983.  
  984.  
  985.  
  986.  
  987.  
  988.                              - 14 -
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.         #define IconCalling
  998.  
  999. to define.h.
  1000.  
  1001.    The implementation of co-expressions requires an assembly-
  1002. language routine.  Initially, define.h contains
  1003.  
  1004.         #define NoCoexpr
  1005.  
  1006. to disable co-expressions during the initial phases of transport-
  1007. ing Icon to a new system.  Leave this definition in for the first
  1008. round, although you may want to remove it later and implement
  1009. co-expressions.  (see Section 7).
  1010.  
  1011. Search path: The -x option requires knowledge of where to find
  1012. iconx.  The path is given in paths.h, which contains the follow-
  1013. ing as distributed:
  1014.  
  1015.         #define IconxPath "iconx.exe"
  1016.  
  1017. This definition can be changed as needed.
  1018.  
  1019. 5.2__Operating_System_Differences
  1020.  
  1021.    Conditional compilation for operating systems usually is due
  1022. to differences in run-time library routines, differences in file
  1023. naming, the handling of input and output, and environmental fac-
  1024. tors.
  1025.  
  1026.    The presently supported operating system are AmigaDos, Atari
  1027. ST TOS, the Macintosh under MPW, MS-DOS, MVS, OS/2, UNIX, and
  1028. VM/CMS, and VMS.  There hooks for transporting to an unspecified
  1029. system (a new port).  The associated defined symbols are
  1030.  
  1031.         AMIGA       AmigaDos
  1032.         ATARI_ST    Atari ST TOS
  1033.         HIGHC_386   MS-DOS in 32-bit protected mode for 80386 processors
  1034.         MACINTOSH   Macintosh
  1035.         MSDOS       MS-DOS
  1036.         MVS         MVS
  1037.         OS          OS/2
  1038.         PORT        new port
  1039.         UNIX        UNIX
  1040.         VM          VM/CMS
  1041.         VMS         VMS
  1042.  
  1043. Conditional compilation uses logical expressions composed from
  1044. these symbols.  An example is:
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.                              - 15 -
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.                 .
  1064.                 .
  1065.                 .
  1066.         #if MSDOS
  1067.                 .
  1068.                 .       /* code for MS-DOS */
  1069.                 .
  1070.         #endif
  1071.  
  1072.         #if UNIX || VMS
  1073.                 .
  1074.                 .       /* code for UNIX and VMS */
  1075.                 .
  1076.         #endif
  1077.                 .
  1078.                 .
  1079.                 .
  1080.  
  1081. Each symbol must be defined to be either 1 (for the target
  1082. operating system) or 0 (for all other operating systems).  This
  1083. is accomplished by defining the symbol for the target operating
  1084. system to be 1 in define.h. In config.h, which includes define.h,
  1085. all other operating-system symbols are automatically defined to
  1086. be 0.
  1087.  
  1088.    Logical conditionals with #if are used instead of defined or
  1089. undefined names with #ifdef to avoid nested conditionals, which
  1090. become very complicated and difficult to understand when there
  1091. are several alternative operating systems.  Note that it is
  1092. important not to use #ifdef accidentally in place of #if, since
  1093. all the names are defined.
  1094.  
  1095.    The file define.h initially contains
  1096.  
  1097.         #define PORT 1
  1098.  
  1099. Leave it as is; later you should come back and change PORT to
  1100. some more appropriate name.
  1101.  
  1102.    Note: The PORT sections contain deliberate syntax errors (so
  1103. marked) to prevent sections from being overlooked during porting.
  1104. These syntax errors must, of course, be removed before compila-
  1105. tion.
  1106.  
  1107.    To make it easy to locate all the places where there is code
  1108. that may be dependent on the operating system, such code is
  1109. bracketed by unique comments of the following form:
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.                              - 16 -
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.         /*
  1130.          * The following code is operating-system dependent.
  1131.          */
  1132.                        .
  1133.                        .
  1134.                        .
  1135.         /*
  1136.          * End of operating-system specific code.
  1137.          */
  1138.  
  1139. Between these beginning and ending comments, the code for dif-
  1140. ferent operating systems is provided using conditional expres-
  1141. sions such as those indicated above.
  1142.  
  1143.    There presently are a total of 43 segments that contain such
  1144. code.  The files that contain operating-system-dependent code are
  1145. listed in Appendix B.  Look through some of the files that con-
  1146. tain such segments to get an idea of what is involved.  Each seg-
  1147. ment contains comments that describe the purpose of the code.  In
  1148. some cases, the most likely code or a suggestion is given in the
  1149. conditional code under PORT.  In some cases, no code will be
  1150. needed. In others, code for an existing system may suffice for
  1151. the new system.
  1152.  
  1153.    In any event, code for the new operating system name must be
  1154. added to each such segment, either by adding it to a logical dis-
  1155. junction to take advantage of existing code for other systems, as
  1156. in
  1157.  
  1158.         #if MSDOS || UNIX || PORT
  1159.              .
  1160.              .
  1161.              .
  1162.         #endif
  1163.  
  1164.         #if VMS
  1165.              .
  1166.              .
  1167.              .
  1168.         #endif
  1169.  
  1170. and removing the present code for PORT or by filling in the seg-
  1171. ment with the appropriate code, as in
  1172.  
  1173.         #if PORT
  1174.                 .
  1175.                 .       /* code for the the port */
  1176.                 .
  1177.         #endif
  1178.  
  1179. If no code for the target operating system, a comment should be
  1180. added so that it is clear that the situation has been considered.
  1181.  
  1182.    You may find need for code that is operating-system dependent
  1183.  
  1184.  
  1185.  
  1186.                              - 17 -
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195. at a place where no such dependency presently exists.  If the
  1196. situation is idiosyncratic to your operating system, which is
  1197. most likely, simply use a conditional for PORT as shown above.
  1198. If the situation appears to need different code for several
  1199. operating systems, add a new segment similar to the other ones,
  1200. being sure to provide something appropriate for all operating
  1201. systems.
  1202.  
  1203.    Do not use #else constructions in these segments; this
  1204. encourages errors and obscures the mutually exclusive nature of
  1205. operating system differences.
  1206.  
  1207.  
  1208. 6.__Building_and_Testing
  1209.  
  1210. 6.1__The_Command_Processor
  1211.  
  1212.    Start by compiling all the C programs listed in icont.bat.
  1213. Link the resulting object files to produce icont.  If you
  1214. encounter problems, first check the portions of code containing
  1215. operating system dependencies.
  1216.  
  1217.    Once you have a version of icont, try it on the Icon programs
  1218. in tests. For example, to translate hello.icn in tests, do
  1219.  
  1220.         icont -c hello.icn
  1221.  
  1222.  
  1223.    The -c option stops icont at the point it produces ucode
  1224. files, which are an intermediate form of virtual machine code.
  1225. This should yield two ucode files, hello.u1 and hello.u2.  The
  1226. .u1 file contains procedure declarations and code for the Icon
  1227. machine; the .u2 file contains global declaration information.
  1228. These files both consist of printable text.  They should be
  1229. identical to the corresponding files in test/stand unless the
  1230. EBCDIC character set is used in the port.
  1231.  
  1232.    Checking icode files is next. Since icode files are binary and
  1233. vary somewhat from system to system, they cannot be checked as
  1234. easily as ucode files. However, as mentioned in Section 5.1, if
  1235. icont is compiled with the linker debugging code enabled, the -L
  1236. command-line option produces a printable image in a file with
  1237. suffix .ux.  For example,
  1238.  
  1239.         icont -L hello.u1
  1240.  
  1241. produces an icode image hello.ux.  Compare this to the
  1242. corresponding file in tests/stand. Remember that differences are
  1243. to be expected and the check is only a rough one.
  1244.  
  1245. 6.2__The_Executor
  1246.  
  1247.    If you get this far without apparent problems, you are ready
  1248. for the next part of the transporting process: iconx.  Compile
  1249.  
  1250.  
  1251.  
  1252.                              - 18 -
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261. all the C programs listed in iconx.bat and load them to form
  1262. iconx.
  1263.  
  1264.    As a first test, try iconx on hello.icn in tests as follows:
  1265.  
  1266.         icont hello.icn
  1267.         iconx hello
  1268.  
  1269. If all is well, the last step should print out "hello world" and
  1270. some identifying information.  If it doesn't, the problem may be
  1271. in either icont or iconx.
  1272.  
  1273.    Once this test has been passed, more rigorous testing should
  1274. follow.  At this point, you probably will want to devise a way of
  1275. testing programs, since there are a large number of tests. This
  1276. is done for the UNIX implementation using the following script:
  1277.  
  1278.         for i in `cat $1.lst`
  1279.         do
  1280.            rm -f local/$i.out
  1281.            echo Running $i
  1282.            icont -s $i.icn
  1283.            if test -r $i.dat
  1284.            then
  1285.               iconx $i <$i.dat >local/$i.out 2>&1
  1286.            else
  1287.               iconx $i >local/$i.out 2>&1
  1288.            fi
  1289.            echo Checking $i
  1290.            diff local/$i.out stand/$i.out
  1291.            rm -f $i
  1292.         done
  1293.  
  1294. Something similar can be concocted for most other systems. Making
  1295. such a facility as easy to use as possible is worth the effort.
  1296.  
  1297.    There are many test programs for testing different aspects of
  1298. iconx. These range from simple tests to ``grinders''. The names
  1299. of the test programs are listed in the following files:
  1300.  
  1301.         check.lst   tests whose results differ from system to systems
  1302.         coexpr.lst  tests that use co-expressions
  1303.         expr.lst    tests that contain a wide variety of expressions
  1304.         float.lst   tests that test floating-point arithmetic
  1305.         gc.lst      tests of garbage collection
  1306.         icon.lst    short but varied tests
  1307.         large.lst   tests of large-integer arithmetic
  1308.         model.lst   tests of features that depend on hashing parameters
  1309.         new.lst     tests of new features
  1310.         other.lst   tests of more complex programs
  1311.  
  1312.  
  1313.    There are data files for all test programs, although some data
  1314. files are empty.  The names of data files correspond to the names
  1315.  
  1316.  
  1317.  
  1318.                              - 19 -
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327. of the Icon programs but end in .dat.  For example, the Icon pro-
  1328. gram meander.icn, listed in icon.lst, takes data from
  1329. meander.dat.  tests/stand contains files whose names end in .out
  1330. that contain the expected output of each test program.  For exam-
  1331. ple, the expected output of meander.icn is contained in
  1332. meander.out.
  1333.  
  1334.    Start with icon.lst. The output should be identical to that in
  1335. the distributed .out files. Any discrepancies should be checked
  1336. carefully and corrections made before continuing.
  1337.  
  1338.    The programs listed in expr.lst execute a wide variety of
  1339. individual expressions. Ideally, there should be no discrepancies
  1340. between their output and the expected output. If there are many
  1341. discrepancies, something serious probably is wrong. If there are
  1342. only a few discrepancies, they may be noted while other testing
  1343. is conducted.
  1344.  
  1345.    The program listed in check.lst certainly will show some
  1346. differences, since they test features whose results are time- and
  1347. environment-dependent.
  1348.  
  1349.    The programs listed in other.lst and new.lst test some
  1350. features that are not tested elsewhere. They should be treated
  1351. like the programs listed in icon.lst.
  1352.  
  1353.    The programs listed in float.lst are likely to show many
  1354. differences, since the routines that convert floating-point
  1355. numbers to strings vary widely from system to system. It is
  1356. enough to check that the numerical magnitudes are correct.
  1357.  
  1358.    The program listed in model.lst shows differences if run on a
  1359. system that has 16-bit ints or if hashing parameters are altered.
  1360.  
  1361.    Since storage management is one of the parts of Icon that is
  1362. likely to give trouble, there are special storage-management
  1363. tests in gc.lst.  These programs run for a long period of time.
  1364. One program may show a difference in output if the fixed-regions
  1365. version of memory management is used, since it may run out of
  1366. space.
  1367.  
  1368.    The programs in large.lst require large-integer arithmetic.
  1369. Run these tests if that feature is supported.
  1370.  
  1371.    The programs in coexpr.lst require co-expressions.  Save them
  1372. for later.
  1373.  
  1374.    Not much general advice can be given about locating and
  1375. correcting problems that may show up in testing iconx. It has to
  1376. be done the hard way and may involve learning more about the Icon
  1377. language [4] and how it is implemented [1].  A good debugger can
  1378. be very helpful.
  1379.  
  1380.    If your system can produce core dumps that are useful for
  1381.  
  1382.  
  1383.  
  1384.                              - 20 -
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393. debugging, set the environment variable ICONCORE. This will cause
  1394. iconx to produce a code dump on abnormal termination.
  1395.  
  1396.  
  1397. 7.__Co-Expressions
  1398.  
  1399.    Once Icon is running satisfactorily, you may wish to implement
  1400. co-expressions.  This requires an assembly-language routine.
  1401.  
  1402.    Note: If your system does not allow the C stack to be at an
  1403. arbitrary place in memory, there is probably little hope of
  1404. implementing co-expressions.  If you do not implement co-
  1405. expressions, the only effect will be that Icon programs that
  1406. attempt to use a co-expression will terminate with an error mes-
  1407. sage.
  1408.  
  1409.    All aspects of co-expression creation and activation are writ-
  1410. ten in C in Version 8 except for a routine, coswitch, that is
  1411. needed for context switching. This routine requires assembly
  1412. language, since it must manipulate hardware registers.  It either
  1413. can be written as a C routine with asm directives or as an assem-
  1414. bly language routine.
  1415.  
  1416.    Calls to the context switch have the form
  1417. coswitch(old_cs,new_cs,first), where old_cs is a pointer to an
  1418. array of words (C longs) that contain C state information for the
  1419. current co-expression, new_cs is a pointer to an array of words
  1420. that hold C state information for a co-expression to be
  1421. activated, and first is 1 or 0, depending on whether or not the
  1422. new co-expression has or has not been activated before.  The
  1423. zeroth element of a C state array always contains the hardware
  1424. stack pointer (sp) for that co-expression. The other elements can
  1425. be used to save any C frame pointers and any other registers your
  1426. C compiler expects to be preserved across calls.
  1427.  
  1428.    The default size of the array for saving the C state is 15.
  1429. This number may be changed by adding
  1430.  
  1431.         #define CStateSize n
  1432.  
  1433. to define.h, where n is the number of elements needed.
  1434.  
  1435.    The first thing coswitch does is to save the current pointers
  1436. and registers in the old_cs array. Then it tests first.  If first
  1437. is zero, coswitch sets sp from new_cs[0], clears the C frame
  1438. pointers, and calls interp. If first is not zero, it loads the
  1439. (previously saved) sp, C frame pointers, and registers from
  1440. new_cs and returns.
  1441.  
  1442.    Written in C, coswitch has the form:
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.                              - 21 -
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.         /*
  1460.          * coswitch
  1461.          */
  1462.         coswitch(old_cs, new_cs, first)
  1463.         long *old_cs, *new_cs;
  1464.         int first;
  1465.         {
  1466.                             .
  1467.                             .
  1468.                             .
  1469.                     /* save sp, frame pointers, and other registers in old_cs */
  1470.                             .
  1471.                             .
  1472.                             .
  1473.            if (first == 0) {          /* this is first activation */
  1474.                             .
  1475.                             .
  1476.                             .
  1477.                     /* load sp from new_cs[0] and clear frame pointers */
  1478.                             .
  1479.                             .
  1480.                             .
  1481.               interp(0, 0);
  1482.               syserr("interp() returned in coswitch");
  1483.               }
  1484.  
  1485.  
  1486.            else {
  1487.                             .
  1488.                             .
  1489.                             .
  1490.                     /* load sp, frame pointers, and other registers from new_cs */
  1491.                             .
  1492.                             .
  1493.                             .
  1494.            }
  1495.         }
  1496.  
  1497.  
  1498.    After you implement coswitch, remove the #define NoCoexpr from
  1499. define.h.
  1500.  
  1501.    To test your context switch, run the programs in coexpr.lst.
  1502. Ideally, there should be no differences in the comparison of out-
  1503. puts.
  1504.  
  1505.    If you have trouble with your context switch, the first thing
  1506. to do is double-check the registers that your C compiler expects
  1507. to be preserved across calls - different C compilers on the same
  1508. computer may have different requirements.
  1509.  
  1510.    Another possible source of problems is built-in stack check-
  1511. ing.  Co-expressions rely on being able to specify an arbitrary
  1512. region of memory for the C stack. If your C compiler generates
  1513.  
  1514.  
  1515.  
  1516.                              - 22 -
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525. code for stack probes that expects the C stack to be at a
  1526. specific location, you may need to disable this code or replace
  1527. it with something more appropriate.
  1528.  
  1529.  
  1530. 8.__Trouble_Reports_and_Feedback
  1531.  
  1532.    If you run into problems, contact us at the Icon Project:
  1533.  
  1534.         Icon Project
  1535.         Department of Computer Science
  1536.         Gould-Simpson Building
  1537.         The University of Arizona
  1538.         Tucson, AZ   85721
  1539.         U.S.A.
  1540.         (602) 621-4049
  1541.         icon-project@cs.arizona.edu     (Internet)
  1542.         ... {uunet, allegra, noao}!arizona!icon-project     (uucp)
  1543.  
  1544.  
  1545.    Please also let us know of any suggestions for improvements to
  1546. the porting process.
  1547.  
  1548.    Once you have completed your port, please send us copies of
  1549. any files that you modified so that we can make corresponding
  1550. changes in the central version of the source code. Once this is
  1551. done, you can get a new copy of the source code whenever changes
  1552. or extensions are made to the implementation.  Be sure to include
  1553. documentation on any features that are not implemented in your
  1554. port or any changes that would affect users.
  1555.  
  1556. Acknowledgements
  1557.  
  1558.    Many persons have been involved in the implementation of Icon.
  1559. Contributions to its portability have been made by Mark Emmer,
  1560. Bill Mitchell, Gregg Townsend, Ken Walker, and Cheyenne Wills.
  1561.  
  1562. References
  1563.  
  1564.  
  1565. 1.   R. E. Griswold and M. T. Griswold, The Implementation of the
  1566.      Icon Programming Language, Princeton University Press, 1986.
  1567.  
  1568. 2.   R. E. Griswold, Installation Guide for Version 8 of Icon on
  1569.      UNIX Systems, The Univ. of Arizona Tech. Rep. 90-2, 1990.
  1570.  
  1571. 3.   R. E. Griswold, Version 8 of Icon, The Univ. of Arizona
  1572.      Tech. Rep. 90-1, 1990.
  1573.  
  1574. 4.   R. E. Griswold and M. T. Griswold, The Icon Programming
  1575.      Language, Prentice-Hall, Inc., Englewood Cliffs, NJ, 1983.
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.                              - 23 -
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591. 5.   R. E. Griswold, An Overview of Version 8 of the Icon
  1592.      Programming Language, The Univ. of Arizona Tech. Rep. 90-6,
  1593.      1990.
  1594.  
  1595. 6.   B. W. Kernighan and D. M. Ritchie, The C Programming
  1596.      Language, Prentice-Hall, Inc., Englewood Cliffs, NJ, 1978.
  1597.  
  1598. 7.   Technical Committee X3J11, Draft Proposed American National
  1599.      Standard for Information Systems -  Programming Language C,
  1600.      1988.
  1601.  
  1602. 8.   R. E. Griswold, ICONT(1), manual page for UNIX Programmer's
  1603.      Manual, The Univ. of Arizona Icon Project Document IPD109,
  1604.      1990.
  1605.  
  1606. 9.   G. M. Townsend, The Icon Memory Monitoring System, The Univ.
  1607.      of Arizona Icon Project Document IPD113, 1990.
  1608.  
  1609. 10.  R. E. Griswold, Icon-C Calling Interfaces, The Univ. of
  1610.      Arizona Tech. Rep. 90-8, 1990.
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.                              - 24 -
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.             Appendix A - Files Used for Components of Icon
  1658.  
  1659.  
  1660.  
  1661. Files marked by * are used in more than one component.
  1662.  
  1663. Files_Used_for_icont
  1664.  
  1665.      config.h*  general configuration information
  1666.      cproto.h*  function prototypes
  1667.      cpuconf.h* processor configuration information
  1668.      define.h*  system-dependent definitions
  1669.      fdefs.h*   function definitions
  1670.      general.h  general header information
  1671.      globals.h  global declarations
  1672.      header.h*  icode header structure
  1673.      keyword.h* keyword definitions
  1674.      lfile.h    information for link declarations
  1675.      link.h     heading information for the linker
  1676.      odefs.h*   operator definitions
  1677.      opcode.h   opcode structure
  1678.      opdefs.h*  icode instruction definitions
  1679.      paths.h*   file paths
  1680.      proto.h*   function prototypes
  1681.      rt.h*      header for run-time system
  1682.      sizes.h    data sizing
  1683.      tlex.h     information for lexical analysis
  1684.      token.h    token definitions
  1685.      tproto.h   function prototypes
  1686.      trans.h    heading information for the translator
  1687.      tree.h     code tree information
  1688.      tsym.h     information for symbol tables
  1689.      version.h* version information
  1690.      ebcdic.c   EBCDIC conversion routines
  1691.      err.c      error messages
  1692.      getopt.c   command-line processing routines
  1693.      keyword.c  keyword structure
  1694.      lcode.c    linker code generator
  1695.      lglob.c    processor for global linking information
  1696.      link.c     linker
  1697.      llex.c     lexical analyzer
  1698.      lmem.c     linker memory management
  1699.      long.c*    long-string routines
  1700.      lnklist.c  file linking
  1701.      lsym.c     linker symbol table management
  1702.      opcode.c   opcode table
  1703.      optab.c    state tables for operator recognition
  1704.      parse.c    parser
  1705.      tcode.c    translator code generator
  1706.      tlex.c     lexical analyzer for translation
  1707.      tlocal.c   local routines
  1708.      tmain.c    main program
  1709.      tmem.c     memory management for translation
  1710.      toktab.c   token table
  1711.  
  1712.  
  1713.  
  1714.                              - 25 -
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.      trans.c    translator
  1724.      tree.c     code tree constructor
  1725.      tsym.c     translator symbol table management
  1726.      util.c     utility routines
  1727.  
  1728. Files_Used_for_iconx
  1729.  
  1730.      config.h*  general configuration information
  1731.      cproto.h*  function prototypes
  1732.      cpuconf.h* computer configuration information
  1733.      define.h*  system-dependent definitions
  1734.      fdefs.h*   function definitions
  1735.      gc.h       garbage collection definitions
  1736.      header.h*  icode header
  1737.      keyword.h* keyword definitions
  1738.      memsize.h* memory sizing
  1739.      odefs.h*   operator definitions
  1740.      opdefs.h*  icode definitions
  1741.      proto.h*   function prototypes
  1742.      rproto.h*  function prototypes
  1743.      rt.h*      run-time definitions
  1744.      version.h* version information
  1745.      extcall.c  external function stub
  1746.      fconv.c    conversion functions
  1747.      fmath.c    math functions
  1748.      fmemmon.c  memory-monitoring functions
  1749.      fmisc.c    miscellaneous functions
  1750.      fscan.c    scanning functions
  1751.      fstr.c     string construction functions
  1752.      fstranl.c  string analysis functions
  1753.      fstruct.c  data structure functions
  1754.      fsys.c     system functions
  1755.      fxtra.c    extra functions
  1756.      idata.c    data
  1757.      imain.c    main program
  1758.      interp.c   icode interpreter
  1759.      invoke.c   function and procedure invocation
  1760.      istart.c   main program for calling Icon from C
  1761.      lmisc.c    miscellaneous library routines
  1762.      long.c*    long-integer routines
  1763.      lrec.c     library routines for record
  1764.      lscan.c    scanning routines
  1765.      memory.c   memory-mangement routines
  1766.      oarith.c   arithmetic operations
  1767.      oasgn.c    assignment operations
  1768.      ocat.c     concatenation operations
  1769.      ocomp.c    comparison operations
  1770.      omisc.c    miscellaneous operations
  1771.      oref.c     referencing operations
  1772.      oset.c     set operations
  1773.      ovalue.c   value operations
  1774.      time.c     time and date routines
  1775.      rcomp.c    comparison routines
  1776.      rconv.c    conversion routines
  1777.  
  1778.  
  1779.  
  1780.                              - 26 -
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.      rdebug.c   debugging routines
  1790.      rdefault.c default value routines
  1791.      rdoasgn.c  assignment routines
  1792.      rlocal.c   local routines
  1793.      rlargint.c large-integer routines
  1794.      rmemexp.c  memory management routines for expandable regions
  1795.      rmemfix.c  memory management routines for fixed regions
  1796.      rmemmgt.c  general memory management routines
  1797.      rmisc.c    miscellaneous routines
  1798.      rstruct.c  structure routines
  1799.      rsys.c     system routines
  1800.  
  1801.  
  1802.  
  1803.  
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.                              - 27 -
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.                Appendix B - System-Dependent Code
  1856.  
  1857.  
  1858.  
  1859.    The following source files contain code that is operating-
  1860. system dependent.  The number of places where such code occurs in
  1861. each file is given in parentheses.
  1862.  
  1863. h:
  1864.  
  1865.  
  1866.         config.h (1)
  1867.         proto.h (1)
  1868.         rt.h (1)
  1869.  
  1870.  
  1871. icont:
  1872.  
  1873.  
  1874.         link.c (3)
  1875.         lmem.c (4)
  1876.         tlocal.c (1)
  1877.         tmain.c (4)
  1878.         util.c (1)
  1879.  
  1880.  
  1881. iconx:
  1882.  
  1883.  
  1884.         fmath.c (1)
  1885.         fsys.c (6)
  1886.         imain.c (6)
  1887.         interp.c (4)
  1888.         rconv.c (1)
  1889.         rlocal.c (1)
  1890.         rmemexp.c (1)
  1891.         rmisc.c (1)
  1892.  
  1893.  
  1894. common:
  1895.  
  1896.  
  1897.         time.c (6)
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.                              - 28 -
  1913.  
  1914.  
  1915.